home *** CD-ROM | disk | FTP | other *** search
/ TPUG - Toronto PET Users Group / TPUG Users Group CD / TPUG Users Group CD.iso / AMIGA / (A)TB / (A)TBK.ADF / Terminal / HandShake_ARexx.doc < prev    next >
Text File  |  1991-02-10  |  11KB  |  250 lines
  1. -----------------
  2.  
  3.       /\/\
  4.      / /  \
  5.  ---/ / /\ \-----
  6.       \/  \ 
  7.  Hand     / Shake  Version 2.20a
  8.  ---\    / /-----
  9.      \  / /
  10.       \/\/
  11.  
  12. -----------------
  13.  
  14. The HandShake/AREXX Interface
  15. -----------------------------
  16.  
  17. HandShake has an AREXX port as of version 2.20a. This allows other
  18. programs to issue commands to HandShake, as well as providing a
  19. script language for HandShake. To use this feature, you must own a
  20. copy of AREXX which is available from you local dealer or directly
  21. from William Hawes.
  22.  
  23. HandShake deals with both AREXX commands and AREXX functions. When
  24. HandShake starts up, it will declare itself as an AREXX function
  25. host. Any AREXX macro which contains calls to the HandShake functions
  26. while HandShake is running will send them to HandShake.
  27.  
  28. In order to send commands to HandShake, it is nesessary to issue an
  29. ADDRESS or SHELL command from the macro of the following form:
  30.  
  31.         ADDRESS 'HANDSHAKE'  or
  32.         SHELL 'HANDSHAKE'
  33.  
  34. Note that the word HANDSHAKE must be in upper case. The name of the
  35. HandShake AREXX port is 'HANDSHAKE'. External programs can send
  36. commands or functions directly by sending correctly formatted Rexx
  37. Messages to this port.
  38.  
  39. Below is a list of the commands which can be sent to HandShake.
  40. NOTE: The case of the command or function name is not important to
  41.       HandShake.
  42.  
  43. COMMANDS
  44. --------
  45. HS_BAUD baud_rate       Sets the baud rate. The baud rate parameter
  46.                         can be any valid Amiga baud rate.
  47.  
  48. HS_COLOR                Causes HandShake to go into color (3 bit
  49.                         plane) mode. This command will fail if any
  50.                         windows are open on the HandShake screen.
  51.  
  52. HS_DATABITS stop_bits   Sets the number of data bits. This parameter
  53.                         must be '7' or '8'.
  54.  
  55. HS_DELAY seconds        Causes macro execution to pause for the
  56.                         specified number of seconds.
  57.  
  58. HS_ENDASCII             Causes an ASCII receive to finish.
  59.  
  60. HS_GETLENGTH            Sets the number of additional characters that
  61.                         are returned with the matched part of a
  62.                         string from the HS_GETSTR command. By default
  63.                         this is set to zero.
  64.  
  65. HS_HANGUP               Hang up the phone (Disconnect from the other
  66.                         host).
  67.  
  68. HS_HIDE                 Place the HandShake screen behind all other
  69.                         screens.
  70.  
  71. HS_MONO                 Causes HandShake to go into monochrome (2 bit
  72.                         plane) mode. This command will fail if any
  73.                         windows are open on the HandShake screen.
  74.  
  75. HS_PARITY parity        Sets the parity. The parameter must be one
  76.                         of: NONE, ODD, EVEN, SPACE, MARK.
  77.  
  78. HS_PROTOCOL protocol    This command sets the file transfer protocol
  79.                         for subsequent file transfers. The protocol
  80.                         must be one of:
  81.                                 ASCII
  82.                                 XMODEM
  83.                                 XMODEM/CRC
  84.                                 YMODEM
  85.                                 YMODEM/BATCH
  86.                                 KERMIT/TEXT
  87.                                 KERMIT/8BIT
  88.                                 KERMIT/7BIT
  89.                                 
  90. HS_SHOW                 Place the HandShake screen in front of all
  91.                         other screens.
  92.  
  93. HS_STOPBITS stop_bits   Sets the number of stop bits. This parameter
  94.                         must be '0' or '1' or '2'.
  95.  
  96. HS_TIMEOUT seconds      This sets the timeout value for the GETSTR()
  97.                         function. If no match is found within the
  98.                         specified number of seconds. The GETSTR()
  99.                         function will abort and return the string
  100.                         HSERR_TIMEOUT.
  101.  
  102. HS_QUIT                 This command will cause HandShake to
  103.                         terminate. It will fail if any windows are
  104.                         open on the HandShake screen.
  105.  
  106. Below is a list of the functions which can be sent to HandShake.
  107. NOTE: The returned value 'r' is a boolean value of '0' for failure or
  108. '1' for success unless otherwise noted.
  109.  
  110. NOTE: When calling AREXX functions, the openning parentheses must
  111. immediately follow the function name with no intervening white space.
  112.  
  113. r = HS_DIAL(dial_str)       This function dials a host system. The
  114.                             dial_str is a string of one of the
  115.                             following forms:
  116.                             'phone_number:baud_rate,data_bits,parity,
  117.                             stop_bits[*]'  or
  118.                             destination_name[*].
  119.                 
  120.                             HandShake makes a decision about which
  121.                             form is being used, based on the first
  122.                             character. if it is a numeric digit. If
  123.                             it is, it is assumed to be a phone_number
  124.                             string. If it is non-numeric, it is
  125.                             assumed to be a destination string.
  126.                 
  127.                             Note that the optional
  128.                             trailing '*' forces auto-redial.
  129.                 
  130.                             Following are some correct dial strings:
  131.                             '123-4567:2400,8,n,1'
  132.                             '1-(555)-555-5555:1200,8,e,1*'
  133.                             "Fred's BBS"
  134.                             'BIX'
  135.                             'John my brother'
  136.                             '555-5555:1200,7,e BIX*'
  137.                             The parameters after the phone number are
  138.                             optional, but they must be specified in
  139.                             the order if present. A destination_name
  140.                             is the name of an entry in the dialing
  141.                             directory.
  142.                 
  143.                             For a more complete description of dial
  144.                             strings,see the file HandShake.doc.
  145.  
  146. r = HS_GETSTR(str1,str2,..) This function waits for one of the
  147. specified strings to arrive on the serial port. The first match will
  148. cause the funtion to return the string that was matched. If
  149. HS_GETLENGTH is set to a non-zero value, that number of additional
  150. characters will be returned with the matched string. HS_GETSTR will
  151. wait for a match for the number of seconds specified by the
  152. HS_TIMEOUT command (see above). Upon completion, it will return
  153. either the matched string plus the next HS_GETLENGTH characters, or
  154. 'HSERR_TIMEOUT' in the event of a timeout.
  155.  
  156. r = HS_LOADPARMS(file_name) Load a parameter file. This is the same
  157. as selecting the load parameters item from the PROJECT menu. This
  158. function will fail if there are any windows open on the HandShake
  159. screen.
  160.  
  161. r = HS_RECEIVE(file_name)   This function causes HandShake to go into
  162. file receive mode. This file is received using the protocol selected
  163. by the PROTOCOL command (see above). If one of the batch protocols
  164. (Kermit or Ymodem Batch) is being used, the file name parameter is
  165. the destination path name and must be terminated with a '/' or a ':'
  166. if ASCII protocol is selected, this function only starts the receive.
  167. To terminate the ASCII receive, use the ENDASCII command described
  168. above.
  169.  
  170. r = HS_SAVEPARMS(file_name) Save current parameters to a file. This
  171. is the same as selecting the save parameters item from the PROJECT
  172. menu.
  173.  
  174. r = HS_STRING(char_str)     This function sends the specified string
  175. out the serial port. No carriage return is sent. A carriage return is
  176. not automatically appended. If you wish to send a carriage return or
  177. any other control character, it must be formatted into the string.
  178. one way of doing this is illustrated below:
  179.             /* Assign some characters to variables.*/
  180.                cr = '0d'x
  181.                esc = '1b'x
  182.             /* Send a string without a carriage return */
  183.                r = hs_string('No carriage return')
  184.             /* Send a string with a carriage return */
  185.                r = hs_string('With carriage return'cr)
  186.             /* Send an escape sequence */
  187.                r = hs_string(esc'[0m')
  188.                 
  189.      The same technique could be used to define an ESCAPE character
  190. for instance. Any Features of the AREXX language can be used to build
  191. the string to be sent.
  192.  
  193. r = HS_TRANSMIT(file_name)  This function causes HandShake to go into
  194. file transmit mode. The file is transmitted using the protocol
  195. selected by the protocol command (see above). If one of the batch
  196. protocols (Kermit of Ymodem Batch) is being used, the file name
  197. parameter can contain AmigaDOS wild card characters.
  198.  
  199.  
  200. INVOKING AREXX MACROS FOR USE WITH HandShake
  201. --------------------------------------------
  202.  
  203. There are five ways to invoke an AREXX macro for use with HandShake:
  204.         1) From a workbench CLI window.
  205.         2) From a HandShake CLI window.
  206.         3) From the RUN MACRO item in the AREXX menu.
  207.         4) From the HandShake command line.
  208.         5) From a HandShake Project icon.
  209.  
  210. The first two methods are the same as running any other AREXX macro
  211. from the command line. In the first case just invoke the macro from
  212. any workbench WSHELL, AmigaShell or CLI window (or anybody elses
  213. shell for that matter.
  214.  
  215. In order to make it easier to run macros (especially those that
  216. require parameters from the command line) HandShake lets you open a
  217. CLI window on the HandShake screen if you have William Hawe's CONMAN
  218. console editing/manager running on your system. This is done by
  219. selecting the DOS window item from the AREXX window. HandShake will
  220. first try to start a WShell ( William Hawe's wonderfull shell), Then
  221. an AmigaShell and finally a CLI window on the HandShake screen. You
  222. can have as many of these DOS windows open as you like. Beware that
  223. some commands or functions sent to HandShake will not work if there
  224. is a window open on the HandShake screen. This is because some
  225. operations cause HandShake to close its screen (either temporarily or
  226. permanently), and this cannot be safely done with windows open on the
  227. screen. If the macro is run from a CLI on the workbench screen all
  228. commands and functions sent to HandShake by AREXX will function
  229. normally.
  230.  
  231. The third method can be used to run any AREXX macro which does not
  232. take any command line parameters. The RUN MACRO menu item will open a
  233. file requester. Just select the file which contains the AREXX macro
  234. which you would like to run. All commands and functions sent from
  235. AREXX to HandShake work when using this method.
  236.  
  237. The Fourth method allows you to have HandShake invoke an AREXX macro
  238. as it starts up. Just specify the -m switch on the command line
  239. followed by the macro name. For instance:
  240.         HandShake -m readbix
  241. will invoke the READBIX.REXX macro. If a dial descriptor is included
  242. on the command line, the dial activity will take place before the
  243. macro is invoked.
  244.  
  245. The fifth method can be used when invoking HandShake from an icon. If
  246. there is a Tool Types array entry in the icon of the form:
  247.         MACRO=READBIX
  248. it will be invoked when HandShake is started. If there is also a
  249. DIALUP= Tool Types entry, the dial activity will happen first.
  250.